<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Linking</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="using_namespaces.html" title="Namespaces" /><link rel="next" href="using_concurrency.html" title="Concurrency" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Linking</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using_namespaces.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="using_concurrency.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.linkage"></a>Linking</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.linkage.freestanding"></a>Almost Nothing</h3></div></div></div><p>
	Or as close as it gets: freestanding. This is a minimal
	configuration, with only partial support for the standard
	library. Assume only the following header files can be used:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
	    <code class="filename">cstdarg</code>
	  </p></li><li class="listitem"><p>
	  <code class="filename">cstddef</code>
	  </p></li><li class="listitem"><p>
	  <code class="filename">cstdlib</code>
	  </p></li><li class="listitem"><p>
	  <code class="filename">exception</code>
	  </p></li><li class="listitem"><p>
	  <code class="filename">limits</code>
	  </p></li><li class="listitem"><p>
	  <code class="filename">new</code>
	  </p></li><li class="listitem"><p>
	  <code class="filename">exception</code>
	  </p></li><li class="listitem"><p>
	  <code class="filename">typeinfo</code>
	  </p></li></ul></div><p>
	In addition, throw in
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
	  <code class="filename">cxxabi.h</code>.
	  </p></li></ul></div><p>
	In the
	C++11 <a class="link" href="using.html#manual.intro.using.flags" title="Command Options">dialect</a> add
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
	  <code class="filename">initializer_list</code>
	  </p></li><li class="listitem"><p>
	  <code class="filename">type_traits</code>
	  </p></li></ul></div><p>
	As of GCC 13, libstdc++ implements P1642, which brings in many more
	headers, as well a quite a few ones not covered by the paper.

	In general, if a feature does not require traditionally libc-provided
	facilities, or dynamic memory allocation, it's enabled in the
	freestanding subset.  In addition, if only a subset of a header
	requires such features, it is partially included.  Some examples
	include:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
	  <code class="filename">string_view</code>
	  </p></li><li class="listitem"><p>
	  <code class="filename">tuple</code>
	  </p></li><li class="listitem"><p>
	  <code class="filename">bitset</code>
	  </p></li></ul></div><p>
	Currently, this subset includes all of the iterator APIs (including the
	ranges APIs) that do not involve streams, the entire C++ algorithms
	library, excluding parallel algorithms, and a large part of the
	utilities library.  This is on top of the headers included in the lists
	above.
      </p><p>
	If you're using a libstdc++ configured for hosted environments, and
	would like to not involve the libraries libstdc++ would depend on in
	your programs, you will need to use <span class="command"><strong>gcc</strong></span> to link your
	application with only <code class="filename">libsupc++.a</code>,
	like so:
      </p><p>
	<span class="command"><strong>gcc -ffreestanding foo.cc -lsupc++</strong></span>
      </p><p>
	If you configured libstdc++ with
	<code class="code">--disable-hosted-libstdcxx</code>, however, you can use the
	normal <span class="command"><strong>g++</strong></span> command to link, as this configuration
	provides a (nearly) empty <code class="filename">libstdc++.a</code>.
      </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.linkage.dynamic"></a>Finding Dynamic or Shared Libraries</h3></div></div></div><p>
      If the only library built is the static library
      (<code class="filename">libstdc++.a</code>), or if
      specifying static linking, this section is can be skipped.  But
      if building or using a shared library
      (<code class="filename">libstdc++.so</code>), then
      additional location information will need to be provided.
    </p><p>
      But how?
    </p><p>
A quick read of the relevant part of the GCC
      manual, <a class="link" href="http://gcc.gnu.org/onlinedocs/gcc/Invoking-G_002b_002b.html#Invoking-G_002b_002b" target="_top">Compiling
      C++ Programs</a>, specifies linking against a C++
      library. More details from the
      GCC <a class="link" href="http://gcc.gnu.org/faq.html#rpath" target="_top">FAQ</a>,
      which states <span class="emphasis"><em>GCC does not, by default, specify a
      location so that the dynamic linker can find dynamic libraries at
      runtime.</em></span>
    </p><p>
      Users will have to provide this information.
    </p><p>
      Methods vary for different platforms and different styles, and
      are printed to the screen during installation. To summarize:
    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
	  At runtime set <code class="literal">LD_LIBRARY_PATH</code> in your
	  environment correctly, so that the shared library for
	  libstdc++ can be found and loaded.  Be certain that you
	  understand all of the other implications and behavior
	  of <code class="literal">LD_LIBRARY_PATH</code> first.
	</p></li><li class="listitem"><p>
	  Compile the path to find the library at runtime into the
	  program.  This can be done by passing certain options to
	  <span class="command"><strong>g++</strong></span>, which will in turn pass them on to
	  the linker.  The exact format of the options is dependent on
	  which linker you use:
	</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
	      GNU ld (default on GNU/Linux):
              <code class="literal">-Wl,-rpath,</code><code class="filename">destdir/lib</code>
	    </p></li><li class="listitem"><p>
	    Solaris ld:
            <code class="literal">-Wl,-R</code><code class="filename">destdir/lib</code>
	  </p></li></ul></div></li><li class="listitem"><p>
	  Some linkers allow you to specify the path to the library by
	  setting <code class="literal">LD_RUN_PATH</code> in your environment
	  when linking.
	</p></li><li class="listitem"><p>
	  On some platforms the system administrator can configure the
	  dynamic linker to always look for libraries in
	  <code class="filename">destdir/lib</code>, for example
	  by using the <span class="command"><strong>ldconfig</strong></span> utility on GNU/Linux
	  or the <span class="command"><strong>crle</strong></span> utility on Solaris. This is a
	  system-wide change which can make the system unusable so if you
	  are unsure then use one of the other methods described above.
	</p></li></ul></div><p>
      Use the <span class="command"><strong>ldd</strong></span> utility on the linked executable
      to show
      which <code class="filename">libstdc++.so</code>
      library the system will get at runtime.
    </p><p>
      A <code class="filename">libstdc++.la</code> file is
      also installed, for use with Libtool.  If you use Libtool to
      create your executables, these details are taken care of for
      you.
    </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.linkage.experimental"></a>Experimental Library Extensions</h3></div></div></div><p>
      GCC 5.3 includes an implementation of the Filesystem library defined
      by the technical specification ISO/IEC TS 18822:2015. Because this is
      an experimental library extension, not part of the C++ standard, it
      is implemented in a separate library,
      <code class="filename">libstdc++fs.a</code>, and there is
      no shared library for it. To use the library you should include
      <code class="filename">&lt;experimental/filesystem&gt;</code>
      and link with <code class="option">-lstdc++fs</code>. The library implementation
      is incomplete on non-POSIX platforms, specifically Windows support is
      rudimentary.
    </p><p>
      Due to the experimental nature of the Filesystem library the usual
      guarantees about ABI stability and backwards compatibility do not apply
      to it. There is no guarantee that the components in any
      <code class="filename">&lt;experimental/xxx&gt;</code>
      header will remain compatible between different GCC releases.
    </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using_namespaces.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="using_concurrency.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Namespaces </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Concurrency</td></tr></table></div></body></html>